from abc import ABC, abstractmethod
from typing import Dict, List, Optional, Any


class IEmbeddingService(ABC):
    """
    嵌入服务接口
    定义嵌入服务应该提供的所有方法
    """
    
    @abstractmethod
    def get_embedding(self, text: str) -> List[float]:
        """
        获取文本的嵌入向量
        
        Args:
            text: 要获取嵌入向量的文本
        
        Returns:
            嵌入向量（浮点数列表）
        """
        pass
    
    @abstractmethod
    def search(self, query: str, category: Optional[str] = None, top_k: int = 5) -> List[Dict[str, Any]]:
        """
        在向量数据库中搜索相似向量
        
        Args:
            query: 搜索查询文本
            category: 可选的分类限制
            top_k: 返回的结果数量
        
        Returns:
            搜索结果列表，每个结果包含文本、分数和元数据
        """
        pass
    
    @abstractmethod
    def add_document(self, text: str, metadata: Optional[Dict[str, Any]] = None, category: Optional[str] = None) -> bool:
        """
        添加文档到向量数据库
        
        Args:
            text: 文档文本
            metadata: 文档元数据
            category: 文档分类
        
        Returns:
            添加是否成功
        """
        pass
    
    @abstractmethod
    def delete_document(self, doc_id: str) -> bool:
        """
        从向量数据库中删除文档
        
        Args:
            doc_id: 文档ID
        
        Returns:
            删除是否成功
        """
        pass
    
    @abstractmethod
    def list_categories(self) -> List[str]:
        """
        列出所有可用的分类
        
        Returns:
            分类名称列表
        """
        pass
    
    @abstractmethod
    def add_category(self, category: str) -> bool:
        """
        添加新分类
        
        Args:
            category: 分类名称
        
        Returns:
            添加是否成功
        """
        pass
    
    @abstractmethod
    def delete_category(self, category: str) -> bool:
        """
        删除分类
        
        Args:
            category: 分类名称
        
        Returns:
            删除是否成功
        """
        pass
    
    @abstractmethod
    def embedding_file(self, file_path: str, file_type: str, metadata: Optional[Dict[str, Any]] = None, category: Optional[str] = None) -> Dict[str, Any]:
        """
        处理文件并生成嵌入
        
        Args:
            file_path: 文件路径
            file_type: 文件类型
            metadata: 文件元数据
            category: 文件分类
        
        Returns:
            处理结果，包含success状态和消息
        """
        pass
    
    @abstractmethod
    def close(self) -> None:
        """
        关闭服务，释放资源
        """
        pass
    
    @abstractmethod
    def embedding_image(self, image_path: str, metadata: Optional[Dict[str, Any]] = None, category: Optional[str] = None) -> Dict[str, Any]:
        """
        处理图像并生成嵌入
        
        Args:
            image_path: 图像路径
            metadata: 图像元数据
            category: 图像分类
        
        Returns:
            处理结果，包含success状态和消息
        """
        pass